{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n# Overview of axes_grid1 toolkit\n\n\nControlling the layout of plots with the axes_grid toolkit.\n\n\nWhat is axes_grid1 toolkit?\n===========================\n\n*axes_grid1* is a collection of helper classes to ease displaying\n(multiple) images with matplotlib.  In matplotlib, the axes location\n(and size) is specified in the normalized figure coordinates, which\nmay not be ideal for displaying images that needs to have a given\naspect ratio.  For example, it helps if you have a colorbar whose\nheight always matches that of the image.  `ImageGrid`_, `RGB Axes`_ and\n`AxesDivider`_ are helper classes that deals with adjusting the\nlocation of (multiple) Axes.  They provides a framework to adjust the\nposition of multiple axes at the drawing time. `ParasiteAxes`_\nprovides twinx(or twiny)-like features so that you can plot different\ndata (e.g., different y-scale) in a same Axes. `AnchoredArtists`_\nincludes custom artists which are placed at some anchored position,\nlike the legend.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png\n   :target: ../../gallery/axes_grid1/demo_axes_grid.html\n   :align: center\n   :scale: 50\n\n   Demo Axes Grid\n\n\naxes_grid1\n==========\n\nImageGrid\n---------\n\n\nA class that creates a grid of Axes. In matplotlib, the axes location\n(and size) is specified in the normalized figure coordinates. This may\nnot be ideal for images that needs to be displayed with a given aspect\nratio.  For example, displaying images of a same size with some fixed\npadding between them cannot be easily done in matplotlib. ImageGrid is\nused in such case.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png\n   :target: ../../gallery/axes_grid1/simple_axesgrid.html\n   :align: center\n   :scale: 50\n\n   Simple Axesgrid\n\n* The position of each axes is determined at the drawing time (see\n  `AxesDivider`_), so that the size of the entire grid fits in the\n  given rectangle (like the aspect of axes). Note that in this example,\n  the paddings between axes are fixed even if you changes the figure\n  size.\n\n* axes in the same column has a same axes width (in figure\n  coordinate), and similarly, axes in the same row has a same\n  height. The widths (height) of the axes in the same row (column) are\n  scaled according to their view limits (xlim or ylim).\n\n  .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png\n     :target: ../../gallery/axes_grid1/simple_axesgrid2.html\n     :align: center\n     :scale: 50\n\n     Simple Axes Grid\n\n* xaxis are shared among axes in a same column. Similarly, yaxis are\n  shared among axes in a same row. Therefore, changing axis properties\n  (view limits, tick location, etc. either by plot commands or using\n  your mouse in interactive backends) of one axes will affect all\n  other shared axes.\n\n\n\nWhen initialized, ImageGrid creates given number (*ngrids* or *ncols* *\n*nrows* if *ngrids* is None) of Axes instances. A sequence-like\ninterface is provided to access the individual Axes instances (e.g.,\ngrid[0] is the first Axes in the grid. See below for the order of\naxes).\n\n\n\nImageGrid takes following arguments,\n\n\n ============= ========   ================================================\n Name          Default    Description\n ============= ========   ================================================\n fig\n rect\n nrows_ncols              number of rows and cols. e.g., (2,2)\n ngrids        None       number of grids. nrows x ncols if None\n direction     \"row\"      increasing direction of axes number. [row|column]\n axes_pad      0.02       pad between axes in inches\n add_all       True       Add axes to figures if True\n share_all     False      xaxis & yaxis of all axes are shared if True\n aspect        True       aspect of axes\n label_mode    \"L\"        location of tick labels thaw will be displayed.\n                          \"1\" (only the lower left axes),\n                          \"L\" (left most and bottom most axes),\n                          or \"all\".\n cbar_mode     None       [None|single|each]\n cbar_location \"right\"    [right|top]\n cbar_pad      None       pad between image axes and colorbar axes\n cbar_size     \"5%\"       size of the colorbar\n axes_class    None\n ============= ========   ================================================\n\n *rect*\n  specifies the location of the grid. You can either specify\n  coordinates of the rectangle to be used (e.g., (0.1, 0.1, 0.8, 0.8)\n  as in the Axes), or the subplot-like position (e.g., \"121\").\n\n *direction*\n  means the increasing direction of the axes number.\n\n *aspect*\n  By default (False), widths and heights of axes in the grid are\n  scaled independently. If True, they are scaled according to their\n  data limits (similar to aspect parameter in mpl).\n\n *share_all*\n  if True, xaxis and yaxis of all axes are shared.\n\n *direction*\n  direction of increasing axes number.  For \"row\",\n\n   +---------+---------+\n   | grid[0] | grid[1] |\n   +---------+---------+\n   | grid[2] | grid[3] |\n   +---------+---------+\n\n  For \"column\",\n\n   +---------+---------+\n   | grid[0] | grid[2] |\n   +---------+---------+\n   | grid[1] | grid[3] |\n   +---------+---------+\n\nYou can also create a colorbar (or colorbars). You can have colorbar\nfor each axes (cbar_mode=\"each\"), or you can have a single colorbar\nfor the grid (cbar_mode=\"single\"). The colorbar can be placed on your\nright, or top. The axes for each colorbar is stored as a *cbar_axes*\nattribute.\n\n\n\nThe examples below show what you can do with ImageGrid.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png\n   :target: ../../gallery/axes_grid1/demo_axes_grid.html\n   :align: center\n   :scale: 50\n\n   Demo Axes Grid\n\n\nAxesDivider Class\n-----------------\n\nBehind the scene, the ImageGrid class and the RGBAxes class utilize the\nAxesDivider class, whose role is to calculate the location of the axes\nat drawing time. While a more about the AxesDivider is (will be)\nexplained in (yet to be written) AxesDividerGuide, direct use of the\nAxesDivider class will not be necessary for most users.  The\naxes_divider module provides a helper function make_axes_locatable,\nwhich can be useful. It takes a existing axes instance and create a\ndivider for it. ::\n\n  ax = subplot(1,1,1)\n  divider = make_axes_locatable(ax)\n\n\n\n\n*make_axes_locatable* returns an instance of the AxesLocator class,\nderived from the Locator. It provides *append_axes* method that\ncreates a new axes on the given side of (\"top\", \"right\", \"bottom\" and\n\"left\") of the original axes.\n\n\n\ncolorbar whose height (or width) in sync with the master axes\n-------------------------------------------------------------\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png\n   :target: ../../gallery/axes_grid1/simple_colorbar.html\n   :align: center\n   :scale: 50\n\n   Simple Colorbar\n\n\n\n\nscatter_hist.py with AxesDivider\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe \"scatter_hist.py\" example in mpl can be rewritten using\n*make_axes_locatable*. ::\n\n    axScatter = subplot(111)\n    axScatter.scatter(x, y)\n    axScatter.set_aspect(1.)\n\n    # create new axes on the right and on the top of the current axes.\n    divider = make_axes_locatable(axScatter)\n    axHistx = divider.append_axes(\"top\", size=1.2, pad=0.1, sharex=axScatter)\n    axHisty = divider.append_axes(\"right\", size=1.2, pad=0.1, sharey=axScatter)\n\n    # the scatter plot:\n    # histograms\n    bins = np.arange(-lim, lim + binwidth, binwidth)\n    axHistx.hist(x, bins=bins)\n    axHisty.hist(y, bins=bins, orientation='horizontal')\n\n\nSee the full source code below.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png\n   :target: ../../gallery/axes_grid1/scatter_hist_locatable_axes.html\n   :align: center\n   :scale: 50\n\n   Scatter Hist\n\n\nThe scatter_hist using the AxesDivider has some advantage over the\noriginal scatter_hist.py in mpl. For example, you can set the aspect\nratio of the scatter plot, even with the x-axis or y-axis is shared\naccordingly.\n\n\nParasiteAxes\n------------\n\nThe ParasiteAxes is an axes whose location is identical to its host\naxes. The location is adjusted in the drawing time, thus it works even\nif the host change its location (e.g., images).\n\nIn most cases, you first create a host axes, which provides a few\nmethod that can be used to create parasite axes. They are *twinx*,\n*twiny* (which are similar to twinx and twiny in the matplotlib) and\n*twin*. *twin* takes an arbitrary transformation that maps between the\ndata coordinates of the host axes and the parasite axes.  *draw*\nmethod of the parasite axes are never called. Instead, host axes\ncollects artists in parasite axes and draw them as if they belong to\nthe host axes, i.e., artists in parasite axes are merged to those of\nthe host axes and then drawn according to their zorder.  The host and\nparasite axes modifies some of the axes behavior. For example, color\ncycle for plot lines are shared between host and parasites. Also, the\nlegend command in host, creates a legend that includes lines in the\nparasite axes.  To create a host axes, you may use *host_subplot* or\n*host_axes* command.\n\n\nExample 1. twinx\n~~~~~~~~~~~~~~~~\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png\n   :target: ../../gallery/axes_grid1/parasite_simple.html\n   :align: center\n   :scale: 50\n\n   Parasite Simple\n\nExample 2. twin\n~~~~~~~~~~~~~~~\n\n*twin* without a transform argument assumes that the parasite axes has the\nsame data transform as the host. This can be useful when you want the\ntop(or right)-axis to have different tick-locations, tick-labels, or\ntick-formatter for bottom(or left)-axis. ::\n\n  ax2 = ax.twin() # now, ax2 is responsible for \"top\" axis and \"right\" axis\n  ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi])\n  ax2.set_xticklabels([\"0\", r\"$\\frac{1}{2}\\pi$\",\n                       r\"$\\pi$\", r\"$\\frac{3}{2}\\pi$\", r\"$2\\pi$\"])\n\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png\n   :target: ../../gallery/axes_grid1/simple_axisline4.html\n   :align: center\n   :scale: 50\n\n   Simple Axisline4\n\n\n\nA more sophisticated example using twin. Note that if you change the\nx-limit in the host axes, the x-limit of the parasite axes will change\naccordingly.\n\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png\n   :target: ../../gallery/axes_grid1/parasite_simple2.html\n   :align: center\n   :scale: 50\n\n   Parasite Simple2\n\n\nAnchoredArtists\n---------------\n\nIt's a collection of artists whose location is anchored to the (axes)\nbbox, like the legend. It is derived from *OffsetBox* in mpl, and\nartist need to be drawn in the canvas coordinate. But, there is a\nlimited support for an arbitrary transform. For example, the ellipse\nin the example below will have width and height in the data\ncoordinate.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png\n   :target: ../../gallery/axes_grid1/simple_anchored_artists.html\n   :align: center\n   :scale: 50\n\n   Simple Anchored Artists\n\n\nInsetLocator\n------------\n\n:mod:`mpl_toolkits.axes_grid1.inset_locator` provides helper classes\nand functions to place your (inset) axes at the anchored position of\nthe parent axes, similarly to AnchoredArtist.\n\nUsing :func:`mpl_toolkits.axes_grid1.inset_locator.inset_axes`, you\ncan have inset axes whose size is either fixed, or a fixed proportion\nof the parent axes. For example,::\n\n    inset_axes = inset_axes(parent_axes,\n                            width=\"30%\", # width = 30% of parent_bbox\n                            height=1., # height : 1 inch\n                            loc='lower left')\n\ncreates an inset axes whose width is 30% of the parent axes and whose\nheight is fixed at 1 inch.\n\nYou may creates your inset whose size is determined so that the data\nscale of the inset axes to be that of the parent axes multiplied by\nsome factor. For example, ::\n\n    inset_axes = zoomed_inset_axes(ax,\n                                   0.5, # zoom = 0.5\n                                   loc='upper right')\n\ncreates an inset axes whose data scale is half of the parent axes.\nHere is complete examples.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png\n   :target: ../../gallery/axes_grid1/inset_locator_demo.html\n   :align: center\n   :scale: 50\n\n   Inset Locator Demo\n\nFor example, :func:`zoomed_inset_axes` can be used when you want the\ninset represents the zoom-up of the small portion in the parent axes.\nAnd :mod:`~mpl_toolkits/axes_grid/inset_locator` provides a helper\nfunction :func:`mark_inset` to mark the location of the area\nrepresented by the inset axes.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png\n   :target: ../../gallery/axes_grid1/inset_locator_demo2.html\n   :align: center\n   :scale: 50\n\n   Inset Locator Demo2\n\n\nRGB Axes\n~~~~~~~~\n\nRGBAxes is a helper class to conveniently show RGB composite\nimages. Like ImageGrid, the location of axes are adjusted so that the\narea occupied by them fits in a given rectangle.  Also, the xaxis and\nyaxis of each axes are shared. ::\n\n    from mpl_toolkits.axes_grid1.axes_rgb import RGBAxes\n\n    fig = plt.figure()\n    ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8])\n\n    r, g, b = get_rgb() # r,g,b are 2-d images\n    ax.imshow_rgb(r, g, b,\n                  origin=\"lower\", interpolation=\"nearest\")\n\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_rgb_001.png\n   :target: ../../gallery/axes_grid1/simple_rgb.html\n   :align: center\n   :scale: 50\n\n   Simple Rgb\n\n\nAxesDivider\n===========\n\nThe axes_divider module provides helper classes to adjust the axes\npositions of a set of images at drawing time.\n\n* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a class of\n  units that are used to determine the size of each axes. For example,\n  you can specify a fixed size.\n\n* :class:`~mpl_toolkits.axes_grid1.axes_size.Divider` is the class\n  that calculates the axes position. It divides the given\n  rectangular area into several areas. The divider is initialized by\n  setting the lists of horizontal and vertical sizes on which the division\n  will be based. Then use\n  :meth:`~mpl_toolkits.axes_grid1.axes_size.Divider.new_locator`,\n  which returns a callable object that can be used to set the\n  axes_locator of the axes.\n\n\nFirst, initialize the divider by specifying its grids, i.e.,\nhorizontal and vertical.\n\nfor example,::\n\n    rect = [0.2, 0.2, 0.6, 0.6]\n    horiz=[h0, h1, h2, h3]\n    vert=[v0, v1, v2]\n    divider = Divider(fig, rect, horiz, vert)\n\nwhere, rect is a bounds of the box that will be divided and h0,..h3,\nv0,..v2 need to be an instance of classes in the\n:mod:`~mpl_toolkits.axes_grid1.axes_size`.  They have *get_size* method\nthat returns a tuple of two floats. The first float is the relative\nsize, and the second float is the absolute size. Consider a following\ngrid.\n\n+-----+-----+-----+-----+\n| v0  |     |     |     |\n+-----+-----+-----+-----+\n| v1  |     |     |     |\n+-----+-----+-----+-----+\n|h0,v2| h1  | h2  | h3  |\n+-----+-----+-----+-----+\n\n\n* v0 => 0, 2\n* v1 => 2, 0\n* v2 => 3, 0\n\nThe height of the bottom row is always 2 (axes_divider internally\nassumes that the unit is inches). The first and the second rows have a\nheight ratio of 2:3. For example, if the total height of the grid is 6,\nthen the first and second row will each occupy 2/(2+3) and 3/(2+3) of\n(6-1) inches. The widths of the horizontal columns will be similarly\ndetermined. When the aspect ratio is set, the total height (or width) will\nbe adjusted accordingly.\n\n\nThe :mod:`mpl_toolkits.axes_grid1.axes_size` contains several classes\nthat can be used to set the horizontal and vertical configurations. For\nexample, for vertical configuration one could use::\n\n  from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled\n  vert = [Fixed(2), Scaled(2), Scaled(3)]\n\nAfter you set up the divider object, then you create a locator\ninstance that will be given to the axes object.::\n\n     locator = divider.new_locator(nx=0, ny=1)\n     ax.set_axes_locator(locator)\n\nThe return value of the new_locator method is an instance of the\nAxesLocator class. It is a callable object that returns the\nlocation and size of the cell at the first column and the second row.\nYou may create a locator that spans over multiple cells.::\n\n     locator = divider.new_locator(nx=0, nx=2, ny=1)\n\nThe above locator, when called, will return the position and size of\nthe cells spanning the first and second column and the first row. In\nthis example, it will return [0:2, 1].\n\nSee the example,\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider2_001.png\n   :target: ../../gallery/axes_grid1/simple_axes_divider2.html\n   :align: center\n   :scale: 50\n\n   Simple Axes Divider2\n\nYou can adjust the size of each axes according to its x or y\ndata limits (AxesX and AxesY).\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png\n   :target: ../../gallery/axes_grid1/simple_axes_divider3.html\n   :align: center\n   :scale: 50\n\n   Simple Axes Divider3\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
